using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using JGSY.CMS.LowCode.Platform.Domain.Entities;

namespace JGSY.CMS.LowCode.Platform.Domain.Interfaces
{
    /// <summary>
    /// 团队仓储接口
    /// 提供团队实体的数据访问抽象，扩展基础仓储功能以支持团队特有的查询和操作
    /// </summary>
    /// <remarks>
    /// 该接口继承自IRepository&lt;Team&gt;，提供基础CRUD操作，
    /// 同时添加了团队业务相关的专用方法：
    /// - 团队名称唯一性验证
    /// - 用户团队关系查询
    /// - 团队成员统计
    /// - 活跃状态筛选
    /// </remarks>
    public interface ITeamRepository : IRepository<Team>
    {
        /// <summary>
        /// 根据名称查找团队
        /// </summary>
        /// <param name="name">团队名称</param>
        /// <returns>匹配的团队实体，不存在时返回null</returns>
        /// <remarks>
        /// 执行精确匹配查询，区分大小写
        /// </remarks>
        Task<Team?> GetByNameAsync(string name);

        /// <summary>
        /// 获取用户所属的团队列表
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <returns>用户参与的所有团队列表</returns>
        /// <remarks>
        /// 返回用户作为成员参与的所有团队，包括不同角色的团队
        /// </remarks>
        Task<List<Team>> GetUserTeamsAsync(long userId);

        /// <summary>
        /// 检查团队名称是否已存在
        /// </summary>
        /// <param name="name">要检查的团队名称</param>
        /// <param name="excludeId">排除的团队ID（用于更新时检查）</param>
        /// <returns>名称已存在返回true，否则返回false</returns>
        /// <remarks>
        /// 用于验证团队名称的唯一性，excludeId用于更新操作时排除当前团队
        /// </remarks>
        Task<bool> IsNameExistsAsync(string name, long? excludeId = null);

        /// <summary>
        /// 获取指定团队的成员数量
        /// </summary>
        /// <param name="teamId">团队ID</param>
        /// <returns>团队的活跃成员数量</returns>
        /// <remarks>
        /// 只统计活跃状态的团队成员，不包括已离开的成员
        /// </remarks>
        Task<int> GetMemberCountAsync(long teamId);

        /// <summary>
        /// 获取所有活跃团队
        /// </summary>
        /// <returns>活跃状态的团队列表</returns>
        /// <remarks>
        /// 返回状态为活跃的团队，用于下拉选择等场景
        /// </remarks>
        Task<List<Team>> GetActiveTeamsAsync();
    }
}
